Variablen, Daten, Referenzen
Variablen erlauben es dir, veränderbare Werte in deinen actions einzusetzen. Variablen sind Platzhalter für Texte, Zahlenwerte oder komplexere Daten, die erst in dem Moment einen festen Wert bekommen, in dem die action ausgeführt wird.
Variablen werden in adaptor:ex durch zwei umschließende eckige Klammern gekennzeichnet. Das sieht dann z.B. so aus:
[[Player.name]]
In dem Moment, in dem wir unser Level designen, ist noch offen, welche Spieler:in (Player) das Level später spielen wird - und somit ist auch der Name (name) noch variabel.
Wird dann eine Session des Levels im Live Modus gestartet und die action ausgeführt, wird [[Player.name]] durch den Namen derjenigen Spieler:in ersetzt, die das Level gerade spielt.
In dieser Twilio Send SMS action nutzen wir eine Variable, um die Ansprache zu personalisieren:
Wird das Level etwa von einer Spieler:in gespielt, für die an einer anderen Stelle der Name 'Ada Lovelace' gespeichert wurde, sieht die sms dann so aus: Hello Ada Lovelace! How is it going?
Variablen können in fast allen actions eingesetzt werden. Du kannst eine variable aus dem VARIABLES-Menü der TOOLBAR in deine action ziehen oder sie selbst eintippen.
In der VARIABLES TOOLBAR findest du die Variablen, die adaptor:ex aus den bestehenden Daten gesammelt hat. Es kann aber auch Variablen geben die dort (noch) nicht aufgelistet sind und die Variablen in der TOOLBAR könnten auch in dem Moment wo sie aufgerufen werden ins Leere verweisen.
Variablen, insbesondere Items, können andere Variablen enthalten. Deshalb ist die TOOLBAR ähnlich einem Dateiverzeichnis aufgebaut. Wenn du eine Variable herüberziehst wird der Pfad, der zur eigentlichen Variable führt ggf. ergänzt.
Es gibt verschiedene Orte in adaptor:ex, an denen variable Daten gespeichert werden, und verschiedene Wege, diese Daten zu referenzieren, also mit Variablen auf diese Daten zu verweisen. Im folgenden findest du heraus, welche Daten und Formen von Referenzen es gibt.
Lokale Variablen
Lokale Variablen sind Daten, die nur für den Verlauf einer Level Session Bestand haben.
Mit der Data action Set etwa kannst du eine lokale Variable erstellen und ihr einen Wert zuweisen, oder eine bereits existierende verändern.
So kannst du z.B. an einer Stelle des Levels die Information speichern, ob eine Spieler:in den linken oder den rechten Weg eingeschlagen hat, um am Ende des Spiels wieder darauf einzugehen.
Später kannst du diese variable dann z.B. in einem Text verwenden oder in der logic action Switch nutzen, um zu bestimmen, mit welchem state es weiter geht.
Level Attributes
In der level -> config kannst du Attributes für dein Level angeben. Attributes ermöglichen es Eigenschaften für dein Level festzulegen.
Adressiere Attributes im entsprechenden Level indem du der variable level voranstellst, z.B.:
[[level.reward]]
Jede Live Session des Levels greift hier auf die selbe variable zu. Wenn also ein Level Attribut in einer Session geändert wird, wird Sie für alle Sessions geändert.
Level Attribute sind gut geeignet um in der Launch Session darauf zurückzugreifen. So kannst du das level, dass gestartet werden soll auf Grund seiner Attribute bestimmen.
Collections und Data Items
Jedes Data Item ist ein Datensatz, der verschiedene Eigenschaften haben kann und einer Sammlung von Items (collection) zugeordnet ist.
Ein guter Einstieg in die Arbeit mit collections und Items ist das Tutorial zum erstellen und verwenden eines Synonymwörterbuchs.
Unter Game -> settings -> collections findest du die Data Items, die derzeit in deinem game existieren. Hier kannst du auch neue Items hinzufügen, die Eigenschaften von bestehenden Items ändern oder eine ganz neue collection erstellen.
Mit der Add Item action kannst du im Laufe eines Levels neue Items in einer deiner Collections erstellen.
Data Items können in jedem Level verwendet werden und bleiben bestehen, auch wenn die session eines Levels beendet wurde. Das ist z.B. wichtig, wenn dein game von verschiedenen Spieler:innen gespielt wird, die im Laufe des Spiels unterschiedliche Fortschritte machen, Punkte sammeln, ihren Namen anpassen und so fort.
Plugins wie telegram und twilio erstellen automatisch neue Items in der players collection, z.B. wenn ein game von einer bisher unbekannten Telefonnummer kontaktiert wird. Deshalb hat jedes adaptor:ex game bereits von Beginn an eine players collection.
Es gibt verschiedene Möglichkeiten, Data Items in einem Level einzusetzen.
Name Reference
Data Items, die eine name Eigenschaft haben, die bereits bekannt ist, können darüber direkt verwendet werden.
[[players.Ada]]
ist ein Verweis auf das Data Item mit der name Eigenschaft Ada in der players collection.
Um eine Eigenschaft des Data Item zu nutzen, fügst du sie mit Punktnotation getrennt hinten an. Etwa:
Hello Ada, your score is [[players.Ada.score]]
Namen, die auf diese Weise verwendet werden, dürfen keine Leerzeichen enthalten.
Inline Query
Der Datenbank-Typ, der adaptor:ex im Hintergrund mit Daten versorgt, erlaubt es, dass wir so genannte find querys verwenden können, um auf items zu verweisen. find queries können sehr komplex und beeindruckend sein. Meist benötigen wir aber nur sehr einfache, leicht verständliche querys, um an die richtigen Daten zu kommen.
Markiere inline querys, indem du sie mit geschweiften Klammern umrandest. Für gewöhnlich verwenden wir einen key und einen value, um eine Anfrage an die Datenbank zu stellen.
[[players.{name:'Ada'}.score]] liefert das gleiche Item und den gleichen Wert wie die obige variable, die mit der name Eigenschaft funktioniert. Wir können mit queries aber mehr tun.
Zum Beispiel können wir auch alle anderen Eigenschaften, die ein item im Laufe des game erhalten hat, nutzen, um es zu identifizieren.
[[players.{location:'At the pub'}.score]] gibt uns den score des players, der oder die sich gerade At the pub aufhält. Beachte, dass der value, solange es sich um einen string handelt, in Anführungszeichen gesetzt werden muss.
Queries bieten viele weitere Möglichkeiten, items zu finden. Wenn du mehr darüber erfahren möchtest, schau dich einmal in der Dokumentation von mongo DB um - der Datenbank typ, mit dem adaptor:ex arbeitet.
Items Referenzieren
Mit der data action Get Item kannst du im Laufe des Levels items mit einem variablen Namen verknüpfen.
Über eine Query (siehe oben) oder die name Eigenschaft des Items, kannst du es adressieren und ihm einen Namen geben, der im Verlauf des Level Gültigkeit hat. Du kannst dann die Eigenschaften des Items per Punkt Notation nutzen. Etwa: [[MyItem.some_value]]
Die folgende Get Item action:
Wird eine Referenz CurrentLocation auf z.B. das folgende Item aus der locations collection erstellen:
Alle folgenden actions in diesem Level können dann mit CurrentLocation auf das Item zugreifen:
Auch einige andere actions (Z.B. Add Item) erlauben es, items, die durch die action erstellt werden, direkt zu referenzieren. Das item wird unabhängig von der level session erstellt und ist auch zum Session-Ende noch vorhanden, es kann aber im level direkt mit dem angegebenen Referenznamen gelesen und geändert werden.
Level Argumente
Wenn eine session von einem level gestartet wird, ist es möglich items als Argumente (arguments) mitzugeben. Das heißt die Referenz auf das Item wird dann erstellt, wenn eine session gestartet wird.
Argumente können in der level config bearbeitet, entfernt und hinzugefügt werden. Hier können wir auch default Referenzen angeben, die in der level session eingesetzt werden, wenn beim Start der level session kein anderes item für dieses argument angegeben wurde.
Jedes level hat zu Beginn bereits ein Player argument definiert. Die weiteren Angaben sind optional. Mit collection kann festgelegt werden, aus welcher Datensammlung das item, das übergeben wird, stammen muss. Default ermöglicht es festzulegen, welches item referenziert wird, wenn beim Start der level session für dieses Argument kein anderes item angegeben wird.
Welches item in einer neu gestarteten level session übergeben wird, wird beim Start der session festgelegt. Wenn du eine session manuell im Live Modus erstellst kannst du die Referenz beim Start angeben. Auch die control action Launch Session erlaubt es über die arguments property, level Argumente anzugeben.
Beim Start einer level session können auch Argumente übergeben werden, die nicht in der level config definiert wurden. Der Referenzname wird dann beim starten der Session oder in der Launch Session action festgelegt.
Um im Level auf das item zuzugreifen, verwenden wir den Namen des Arguments. Wie auch bei anderen Item Referenzen können wir darüber die Item Eigenschaften einsetzen, verändern und neue hinzufügen. Wollen wir etwa die phone_number-Eigenschaft des Player Arguments nutzen, verwenden wir, wie bei name- und query-Referenzen, Punktnotation.
[[Player.phone_number]]
Je nachdem, welches players item beim level session start manuell oder automatisch übergeben wurde, bezieht sich [[Player.phone_number]] auf die Eigenschaft phone_number des jeweiligen players.
Plugins wie telegram und twilio übergeben automatisch Level-Argumente, wenn es eingehende Nachrichten von Kontakten gibt, für die bisher kein level läuft. Wird so ein default level gestartet, wird überprüft, ob in der players collection ein item mit entsprechenden Kontaktdaten (z.B. einer Telefonnummer) existiert, um dieses item an die level session als 'Player' argument weiterzugeben. Existiert kein passendes item, wird ein neues erstellt und dann an die level session als Player Argument weitergegeben.
Wenn du mit Get Item oder einer anderen action eine Referenz erstellst, die den selben Namen hat wie eines der Level Argumente, wird das Argument mit der neuen Referenz überschrieben.
Mehrere Items referenzieren
Es ist möglich mit einem Referenz Namen auf mehrere Items gleichzeitig zu verweisen. Das kann der Fall sein wenn du etwa eine Inline Query oder die find query in Get Item so formulierst, dass sie mehreren Items in einer collection zugeordnet werden kann.
Die query players.{score:3} verweist auf alle Items in der players collection, die einen score von 3 haben. Das können keine, 1 oder mehrere Items sein.
Die query players.{} verweist sogar auf alle Items die sich in der players collection befinden.
Nutzt du eine query, die auf mehrere Items verweist etwa in der Set action, werden die variablen in allen Items auf die die query verweist geändert oder erstellt.
Alle DATA actions erlauben es dir mit der Settings option multiple items, anzugeben ob jeweils alle Items oder nur 1 Item angepasst, gelöscht oder geladen werden soll.
Einige Actions verwenden immer nur 1 Item, auch wenn mehrere items referenziert werden. Das ist etwa der Fall, wenn eine variable eines Items z.B. in einem Text eingesetzt wird.
Z.B.: Auch wenn players.{score:3} auf mehrere Items in der players Kollektion verweist, wird [[players.{score:3}.name]] nur einen name ausgeben.
Wenn du sicherstellen willst welche variable verwendet wird versuche die entsprechende query genauer zu formulieren.
Action Data
Einige actions speichern Daten ab, die während des Spiels anfallen, und ermöglichen es so, im Laufe des Levels darauf zuzugreifen.
Solche action Daten sind über das keyword state, den State-Namen, in dem die action sich befindet, und den Namen der action lesbar:
[[state.MyState.onSms_1.text]] enthält, sobald der state MyState getriggert wurde und eine SMS eingegangen ist, den Text dieser SMS.
Das VARIABLES-Menü in der Sidebar zeigt dir an, welche deiner actions im Laufe des Levels Daten enthalten können und wie sie adressiert werden.
Functions
Es ist auch möglich die Palette der functions, die sich einfach erweitern lässt, zu nutzen, um Texte variabel zu ergänzen, Bedingungen zu überprüfen oder items zu verändern.
Eine function variable wird, wenn die entsprechende action ausgeführt wird, mit dem jeweiligen Rückgabewert (return value) der Funktion ersetzt.
Es ist jetzt [[functions.getTime()]] Uhr ergibt also z.B. Es ist jetzt 16:00 Uhr.
Du findest alle zur Verfügung stehenden functions in der VARIABLES TOOLBAR unter FUNCTIONS.
Im Kapitel Javascript Funktionen erfährst du wie du Funktionen einsetzt und wie du eigene Funktionen erstellen und zu deinem adaptor:ex Game hinzufügen kannst.
Fehlende und leere Variablen
Führt eine Variable zu keinem Wert oder keinem item ist sie undefined. Das kann der Fall sein, weil die referenzierte Eigenschaft oder das item (noch) nicht existiert, oder weil die variable einen (Tipp-)Fehler enthält.
In einem Text, der eine leere oder fehlende Variable enthält, wird an dieser stelle auch undefined ergänzt. Etwa: 'Hallo [[Player.name]]!' würde, wenn kein Player existiert oder Player keine name Eigenschaft hat, zu Hallo undefined!